<!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta name="robot" content="index,follow">
<title>Module xis - XML/HTML reader - Forth Foundation Library</title>
</head>
<body>
<h2>xis - XML/HTML reader</h2>
<h3>Module Description</h3>
<p>The xis module implements a non-validating XML/HTML parser.
The default entity references, &lt; &gt; &amp;, &quot; and ' are
translated, all others are simply returned in the text. By using the
xis-msc! word a message catalog can be set, that will overrule the default
translations of entity references. The xis-set-reader word expects an
execution token with the following stack behavior:
<pre>
   x -- c-addr u | 0
</pre>
Data x is the same as the first parameter during calling of the word
xis-set-reader. For reading from files this is normally the file
descriptor. The word returns, if successful, the read data in c-addr u.
The xis-read word returns the parsed xml token with the following varying
stack parameters:
<pre>
xis.error          --
xis.done           --
xis.start-xml      -- c-addr1 u1 .. c-addrn un n          = Return n attribute names with their value
xis.comment        -- c-addr u                            = Return the comment
xis.text           -- c-addr u                            = Return the normal text
xis.start-tag      -- c-addr1 u1 .. c-addrn un n c-addr u = Return the tag name and n attributes with their value
xis.end-tag        -- c-addr u                            = Return the tag name
xis.empty-element  -- c-addr1 u1 .. c-addrn un n c-addr u = Return the tag name and n attributes with their value
xis.cdata          -- c-addr u                            = Return the CDATA section text
xis.proc-instr     -- c-addr1 u1 .. c-addrn un n c-addr u = Return the target name and n attributes with their value
xis.internal-dtd   -- c-addr1 u1 c-addr2 u2               = Return the DTD name c-addr2 u2 and markup c-addr1 u1
xis.public-dtd     -- c-addr1 u1 c-addr2 u2 c-addr3 u3 c-addr4 u4 = Return the DTD name, the markup, the system-id and public-id
xis.system-dtd     -- c-addr1 u1 c-addr2 u2 c-addr3 u3    = Return the DTD name, the markup and the system-id
</pre>
</p>
<h3>Module Words</h3>
<dl>
</dl>
<h4>xis reader constants</h4>
<dl>
<dt><a name="word1"><b>xis.error</b>	( -- n )</dt>
<dd>Error</dd>
<dt><a name="word2"><b>xis.done</b>	( -- n )</dt>
<dd>Done reading</dd>
<dt><a name="word3"><b>xis.start-xml</b>	( -- n )</dt>
<dd>Start Document</dd>
<dt><a name="word4"><b>xis.comment</b>	( -- n )</dt>
<dd>Comment</dd>
<dt><a name="word5"><b>xis.text</b>	( -- n )</dt>
<dd>Normal text</dd>
<dt><a name="word6"><b>xis.start-tag</b>	( -- n )</dt>
<dd>Start tag</dd>
<dt><a name="word7"><b>xis.end-tag</b>	( -- n )</dt>
<dd>End tag</dd>
<dt><a name="word8"><b>xis.empty-element</b>	( -- n )</dt>
<dd>Empty element</dd>
<dt><a name="word9"><b>xis.cdata</b>	( -- n )</dt>
<dd>CDATA section</dd>
<dt><a name="word10"><b>xis.proc-instr</b>	( -- n )</dt>
<dd>Proc. instr.</dd>
<dt><a name="word11"><b>xis.internal-dtd</b>	( -- n )</dt>
<dd>Internal DTD</dd>
<dt><a name="word12"><b>xis.public-dtd</b>	( -- n )</dt>
<dd>Public DTD</dd>
<dt><a name="word13"><b>xis.system-dtd</b>	( -- n )</dt>
<dd>System DTD</dd>
</dl>
<h4>xml reader structure</h4>
<dl>
<dt><a name="word14"><b>xis%</b>	( -- n )</dt>
<dd>Get the required space for a xis reader variable</dd>
</dl>
<h4>xml reader variable creation, initialisation and destruction</h4>
<dl>
<dt><a name="word15"><b>xis-init</b>	( xis -- )</dt>
<dd>Initialise the xml reader variable</dd>
<dt><a name="word16"><b>xis-(free)</b>	( xis -- )</dt>
<dd>Free the internal, private variables from the heap</dd>
<dt><a name="word17"><b>xis-create</b>	( "&lt;spaces&gt;name" -- ; -- xis )</dt>
<dd>Create a named xml reader variable in the dictionary</dd>
<dt><a name="word18"><b>xis-new</b>	( -- xis )</dt>
<dd>Create a new xml reader variable on the heap</dd>
<dt><a name="word19"><b>xis-free</b>	( xis -- )</dt>
<dd>Free the xis reader variable from the heap</dd>
</dl>
<h4>xml reader init words</h4>
<dl>
<dt><a name="word20"><b>xis-set-reader</b>	( x xt xis -- )</dt>
<dd>Init the xml parser for reading using the reader callback xt with its data x</dd>
<dt><a name="word21"><b>xis-set-string</b>	( c-addr u xis -- )</dt>
<dd>Init the xml parser for for reading from the string c-addr u</dd>
</dl>
<h4>Member words</h4>
<dl>
<dt><a name="word22"><b>xis-msc@</b>	( xis -- msc )</dt>
<dd>Get the current entity reference catalog</dd>
<dt><a name="word23"><b>xis-msc!</b>	( msc xis -- )</dt>
<dd>Set the entity reference catalog for the reader</dd>
<dt><a name="word24"><b>xis-strip@</b>	( xis -- flag )</dt>
<dd>Return flag indicating the stripping of leading and trailing white space in normal text</dd>
<dt><a name="word25"><b>xis-strip!</b>	( flag xis -- )</dt>
<dd>Set the flag indicating the stripping of leading and trailing white space in normal text</dd>
</dl>
<h4>xml reader word</h4>
<dl>
<dt><a name="word26"><b>xis-read</b>	( xis -- i*x n )</dt>
<dd>Read the next xml token n with various parameters from the source (see xml reader constants)</dd>
<dt><a name="word27"><b>xis+remove-read-parameters</b>	( i*x n -- )</dt>
<dd>Remove the various parameters of a xml token after calling xis-read (see xml reader constants)</dd>
<dt><a name="word28"><b>xis+dump-read-parameters</b>	( i*x n -- )</dt>
<dd>Dump the various parameters of a xml token after calling xis-read (see xml reader constants)</dd>
</dl>
<h3>Examples</h3>
<pre>
include ffl/xis.fs


\ Example: Read a XML/HTML file

\ Create a XML/HTML input stream on the heap

xis-new value xis1


\ Setup the reader callback word for reading from file

: file-reader ( fileid -- c-addr u | 0 )
  pad 64 rot read-file throw
  dup IF
    pad swap
  THEN
;



s" test.xml" r/o open-file throw value xis.file  \ Open the file

xis.file  ' file-reader   xis1 xis-set-reader     \ Use the xml reader with a file

true xis1 xis-strip!                              \ Strip leading and trailing whitespace in the text

: file-parse  ( -- = Parse the xml file )
  BEGIN
    xis1 xis-read                           \ Read the next token from the file
    dup xis.error &lt;&gt; over xis.done &lt;&gt; AND   \ Done when ready or error
  WHILE
    xis+dump-read-parameters                \ Dump the next token with its parameters
   
  REPEAT
  
  xis.error = IF
    ." Error parsing the file." cr
  ELSE
    ." File succesfully parsed." cr
  THEN
;

\ Parse the file

file-parse


\ Done, close the file

xis.file close-file throw


\ Free the stream from the heap

xis1 xis-free

</pre>
<hr>
<div align="center">generated 24-Jul-2010 by <b>ofcfrth-0.10.0</b></div>
</body>
</html>
